Collection of Tools & Utilities/Collection of Tools and Utilities.iso/asmutil/a86v400.zip/A13.DOC

Text File | 1994-12-21 | 18KB | 365 lines

CHAPTER 13   ASSOCIATED TOOLS AND OUTPUT FILES


Listings with A86

A86 has a powerful listing facility, that allows you to tailor
the format of your listings to your specific needs.  Because the
listing pass adds a significant percentage to the time it takes
A86 to execute, the listing is not produced by default.  You must
include either a +L switch, or the name of a file with a .LST
extension on the A86 invocation line.

By default (+L but nothing else specified), an A86 listing file
consists of a sequence of pages, each 59 lines long and 79
characters wide.  Each page has a header line identifying A86 and
its version number, giving the name of the program output file,
the date and time of assembly, the name of the source file
currently being listed, and a page number.  Note that I am not so
obnoxious as to splash my company name over the top of every page
of your listing!  If both a TITLE and a SUBTTL have been
specified, the header consists of three content lines and one
skipped line; otherwise, there are just two content lines.  Each
listing line has a sequential line number, a hex offset and hex
object bytes, an indicator field with "i" for include files and
"m" for macro expansions, and the source code itself.  Nested
includes have no special indication; nested macros are indicated
by increasing indentation of the macro expansion line.  A86 tries
to be intelligent about the formatting of its listings: it will
break up the wraparound of a long line at a word if reasonable.
It will avoid breaking up a multi-line listing of less than 10
lines.  It will break pages at sensible locations (described in
detail shortly, under the PAGE directive).  It will suppress
blank lines at the top and bottom of pages (but it counts them in
the sequential line numbering so you can tell they were there).

Five A86 switches, H, I, L, T, and W, allow you to control the
existence and characteristics of titling, pagination, page-number
format, page break control, source line numbering, hex object
display, and source line display.  The operation of these
switches is described in detail in Chapter 3.  Here are some
examples of switch settings that will produce listings meeting
some specialized needs:

+L21+T0+W12+I137 produces a listing consisting only of the source
code, with the hex offset of each line placed to the left, and
with the line truncated at 79 columns.  Such a listing file would
be ideal for viewing the source file while debugging on a
primitive remote system that cannot run D86.

+L9+T0+W4+I128 produces a list file of just source code, with all
conditional-assembly lines and skipped code removed.  All
titling, pagination, line numbers, and hex codes are eliminated,
so the list file could be renamed as a source file, and
reassembled.  This might be useful for archival purposes, or for
giving individualized versions of a source file to parties who
don't need any of the conditional-assembly options you've
programmed.
                                                             13-2

+L+I186+H15+W12 produces a list file that concentrates on the hex
output, increasing the width to 16 bytes per line, showing up to
15 hex runover lines, and limiting the amount of source code
shown.


Listing Control Directives

In addition to the five switches just mentioned, A86 has a number
of source-code directives that control aspects of listings.

The .NOLIST directive causes all subsequent listing to be
suppressed, until a .LIST directive is seen.  Line numbering and
page numbering continues during list suppression, so the result
is as if you had text-edited the listing file to remove all the
suppressed lines.

I also offer a macro-definition control code, #H, which causes
the suppression of the listing of macro expansion lines.  If #H
appears anywhere within a macro definition, all calls to that
macro will be listed as the macro call line only, showing the
generated hex object bytes on that call line.  This allows you to
define macros that will be listed as if they were simple machine
instructions.  This effect can be achieved for all macros with an
L switch setting that doesn't include the value 4 (see Chapter
3).

The TITLE directive specifies a title that will appear at the top
of every page of the entire assembly.  The title consists of the
first 60 characters starting with the first nonblank after the
word TITLE on the line.  If you give more than one TITLE
directive in a program, only the first will be recognized.

The SUBTTL directive specifies a subtitle to appear at the top of
every page until another SUBTTL directive is given (or until the
next file change if you have the +T16 switch-bit value set).  If
the directive is at the very top of the listing page, or it is
shortly after an automatic page break, the subtitle will take
effect on the page in which it appears.  Otherwise, it will take
effect at the next page.

The PAGE directive serves several purposes.  The word PAGE by
itself will force a new page in the listing, at that point.  A
plus sign following the word PAGE causes a new page plus an
incremented section number -- e.g. PAGE + on page 1-17 will cause
a new page 2-1 to begin.  The word PAGE followed by one or more
constant parameters will set various A86 listing variables to the
specified parameter values.  The variables are as follows:

1. The length, in lines, of a listing page.  Minimum is 10;
   maximum is 65535.

2. The width, in characters, of the maximum listing line.

3,4,5,6. The number of lines at the end of a page, less than
   which A86 guarantees will not be "widowed" after a page break
   of level 1,2,3,4, respectively.
                                                             13-3

Omitted parameters (either left off the end or via leading commas
or 2 consecutive commas) will remain unchanged.

The concept of "page break levels" is unique to A86 listings: it
is my attempt to get A86 to make intelligent decisions about
where to issue new listing pages.  There are 4 page break levels,
normally triggered by gaps (consecutive blank lines) in the
source code, and by source-file changes.  One- and two-line gaps
cause breaks of level 1 and 2, respectively.  Three-or-more-line
gaps cause a break of level 3.  A source-file change causes a
break of level 4.  If a page break occurs close to the end of a
page, and a break of greater level hasn't already been marked,
A86 will mark the point for a potential new page.  If a page
break of equal or greater level doesn't occur before the page is
full, A86 will issue a new page at the marked point.  The
definition of "close to the end of the page" is 10,20,30, and 40
lines, respectively, for break levels 1,2,3,4.  Those line counts
can be changed by parmeters 3,4,5,6 of the PAGE directive, as
already described.

If you are intimidated by all this, or if you want to control
page break levels manually, you may specify a T switch value that
does not include the "auto-paging" option value 4.  With that
option disabled, page break levels will occur only at places
where you issue a PAGE directive containing a special parameter
value /1, /2, /3, or /4.  The leading slash indicates that a page
break of the indicated level is desired here.  Such a parameter
will typically be given by itself following PAGE; but, if you
wish, it can be interspersed anywhere among other parameter
values -- it will not be "counted" for the purposes of
determining the other parameters' positions.



Cross-reference Facility


When you specify the +X switch, A86 will create a
cross-referenced symbol table listing of your program.

The output file, having a standard extension of .XRF is an
alphabetical listing of all the non-local symbols in your
program.  For each symbol, A86 gives its type, the file in which
it was defined, its value, and a list of all procedures in which
the file was used.  If you print this file, you typically use the
TCOLS tool to obtain a multi-column listing from A86's
single-column output.

Note the use of procedure names to identif